package com.example.docmanagement.controller;

import com.example.docmanagement.dto.request.DocumentCreateRequest;
import com.example.docmanagement.dto.request.DocumentQueryRequest;
import com.example.docmanagement.dto.request.DocumentUpdateRequest;
import com.example.docmanagement.dto.response.ApiResponse;
import com.example.docmanagement.dto.response.DocumentResponse;
import com.example.docmanagement.dto.response.PageResponse;
import com.example.docmanagement.service.DocumentService;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.tags.Tag;
import jakarta.validation.Valid;
import lombok.RequiredArgsConstructor;
import org.springdoc.core.annotations.ParameterObject;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

/**
 * 文档管理控制器
 * 提供文档的完整生命周期管理功能
 * 
 * 基础路径：/api/v1/documents
 * 
 * 主要功能：
 * - 文档列表查询（支持分页、筛选、搜索、排序）
 * - 文档详情查看（根据slug）
 * - 文档创建
 * - 文档更新
 * - 文档删除
 * - 浏览量统计
 * 
 * 支持的内容类型：
 * - Markdown直接内容
 * - 文件路径引用
 * - 外部URL引用
 * - Base64编码内容
 */
@RestController
@RequestMapping("/api/v1/documents")
@RequiredArgsConstructor
@Tag(name = "文档管理", description = "文档的增删改查接口")
public class DocumentController {

    private final DocumentService documentService;

    /**
     * 获取文档列表接口
     * 
     * 接口路径：GET /api/v1/documents
     * 
     * 功能说明：
     * - 分页查询文档列表
     * - 支持按分类、状态、标签筛选
     * - 支持关键词搜索（标题、摘要、内容）
     * - 支持多字段排序
     * 
     * 请求示例：
     * GET
     * /api/v1/documents?page=1&pageSize=20&categoryId=1&status=published&keyword=Java&tags=教程,入门&sortBy=viewCount&sortOrder=desc
     * 
     * 查询参数说明：
     * - page: 页码（从1开始，默认1）
     * - pageSize: 每页数量（默认10，建议1-100）
     * - categoryId: 分类ID筛选（可选）
     * - status: 状态筛选（draft/published/archived，可选）
     * - keyword: 搜索关键词（可选）
     * - tags: 标签筛选，逗号分隔（可选）
     * - sortBy:
     * 排序字段（createdAt/updatedAt/publishedAt/viewCount/likeCount/title，默认createdAt）
     * - sortOrder: 排序方向（asc/desc，默认desc）
     * 
     * 响应示例：
     * {
     * "success": true,
     * "data": {
     * "data": [
     * {
     * "id": 1,
     * "title": "Java入门指南",
     * "slug": "java-getting-started",
     * "summary": "适合初学者的Java教程",
     * "categoryId": 1,
     * "categoryName": "编程语言",
     * "tags": ["java", "入门"],
     * "status": "published",
     * "viewCount": 1523,
     * "createdAt": "2024-01-10T08:00:00"
     * }
     * ],
     * "page": 1,
     * "pageSize": 20,
     * "total": 100,
     * "totalPages": 5,
     * "hasNext": true,
     * "hasPrevious": false
     * },
     * "message": "操作成功"
     * }
     *
     * @param request 查询请求参数，包含分页、筛选、排序等条件
     * @return 包含文档列表和分页信息的响应
     */
    @GetMapping
    @Operation(summary = "获取文档列表", description = "支持分页、筛选、排序")
    public ResponseEntity<ApiResponse<PageResponse<DocumentResponse>>> getDocuments(
            @ParameterObject @ModelAttribute DocumentQueryRequest request) {
        PageResponse<DocumentResponse> page = documentService.getDocuments(request);
        return ResponseEntity.ok(ApiResponse.success(page));
    }

    /**
     * 获取文档详情接口
     * 
     * 接口路径：GET /api/v1/documents/{slug}
     * 
     * 功能说明：
     * - 根据slug获取文档完整信息
     * - 自动增加浏览量计数
     * - 返回渲染后的HTML内容
     * 
     * 请求示例：
     * GET /api/v1/documents/java-getting-started
     * 
     * 响应示例：
     * {
     * "success": true,
     * "data": {
     * "id": 1,
     * "title": "Java入门指南",
     * "slug": "java-getting-started",
     * "summary": "适合初学者的Java教程",
     * "content": "# Java入门\n\n这是内容...",
     * "contentHtml": "
     * <h1>Java入门</h1>
     * <p>
     * 这是内容...
     * </p>
     * ",
     * "contentType": "direct",
     * "categoryId": 1,
     * "categoryName": "编程语言",
     * "tags": ["java", "入门", "教程"],
     * "status": "published",
     * "isPublic": true,
     * "version": 3,
     * "language": "zh-CN",
     * "authorId": "550e8400-e29b-41d4-a716-446655440000",
     * "author": "张三",
     * "viewCount": 1524,
     * "likeCount": 89,
     * "publishedAt": "2024-01-15T10:30:00",
     * "createdAt": "2024-01-10T08:00:00",
     * "updatedAt": "2024-01-20T14:20:00"
     * },
     * "message": "操作成功"
     * }
     *
     * @param slug 文档的唯一标识符
     * @return 包含文档完整信息的响应
     */
    @GetMapping("/{slug}")
    @Operation(summary = "获取文档详情", description = "根据 slug 获取文档详情，自动增加浏览量")
    public ResponseEntity<ApiResponse<DocumentResponse>> getDocument(
            @Parameter(description = "文档唯一标识 slug", required = true, example = "java-getting-started")
            @PathVariable String slug) {
        DocumentResponse document = documentService.getDocumentBySlug(slug);
        return ResponseEntity.ok(ApiResponse.success(document));
    }

    /**
     * 根据ID获取文档详情接口（用于编辑）
     * 
     * 接口路径：GET /api/v1/documents/id/{id}
     * 
     * 功能说明：
     * - 根据ID获取文档完整信息（不增加浏览量）
     * - 主要用于文档编辑页面
     * 
     * @param id 文档ID
     * @return 包含文档完整信息的响应
     */
    @GetMapping("/id/{id}")
    @Operation(summary = "根据ID获取文档详情", description = "根据ID获取文档，用于编辑，不增加浏览量")
    public ResponseEntity<ApiResponse<DocumentResponse>> getDocumentById(
            @Parameter(description = "文档ID", required = true, example = "1") @PathVariable Long id) {
        DocumentResponse document = documentService.getDocumentById(id);
        return ResponseEntity.ok(ApiResponse.success(document));
    }

    /**
     * 创建文档接口
     * 
     * 接口路径：POST /api/v1/documents
     * 权限要求：需要登录认证
     * 
     * 功能说明：
     * - 创建新文档
     * - 自动生成文档ID和创建时间
     * - 自动关联当前登录用户为作者
     * - 支持多种内容类型（direct/file/url/base64）
     * 
     * 请求示例：
     * POST /api/v1/documents
     * Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
     * Content-Type: application/json
     * 
     * {
     * "title": "Java入门指南",
     * "slug": "java-getting-started",
     * "summary": "适合初学者的Java教程",
     * "content": "# Java入门\n\n这是内容...",
     * "contentType": "direct",
     * "categoryId": 1,
     * "tags": ["java", "入门", "教程"],
     * "status": "published",
     * "isPublic": true,
     * "language": "zh-CN"
     * }
     * 
     * 响应示例：
     * {
     * "success": true,
     * "data": {
     * "id": 1,
     * "title": "Java入门指南",
     * "slug": "java-getting-started",
     * ...
     * },
     * "message": "文档创建成功"
     * }
     *
     * @param request 文档创建请求，包含标题、内容等信息
     * @return 包含新创建文档信息的响应，HTTP状态码201
     */
    @PostMapping
    @Operation(summary = "创建文档", description = "创建新文档")
    public ResponseEntity<ApiResponse<DocumentResponse>> createDocument(
            @Valid @RequestBody DocumentCreateRequest request) {
        DocumentResponse document = documentService.createDocument(request);
        return ResponseEntity
                .status(HttpStatus.CREATED)
                .body(ApiResponse.success(document, "文档创建成功"));
    }

    /**
     * 更新文档接口
     * 
     * 接口路径：PUT /api/v1/documents/{id}
     * 权限要求：需要登录认证，且为文档作者或管理员
     * 
     * 功能说明：
     * - 更新现有文档信息
     * - 支持部分更新（只传需要修改的字段）
     * - 自动更新修改时间
     * - 版本号自动递增
     * 
     * 请求示例：
     * PUT /api/v1/documents/1
     * Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
     * Content-Type: application/json
     * 
     * {
     * "title": "Java进阶指南",
     * "status": "published",
     * "tags": ["java", "进阶", "教程"]
     * }
     * 
     * 响应示例：
     * {
     * "success": true,
     * "data": {
     * "id": 1,
     * "title": "Java进阶指南",
     * "version": 4,
     * "updatedAt": "2024-01-21T09:30:00",
     * ...
     * },
     * "message": "文档更新成功"
     * }
     *
     * @param id      文档ID
     * @param request 文档更新请求，包含需要更新的字段
     * @return 包含更新后文档信息的响应
     */
    @PutMapping("/{id}")
    @Operation(summary = "更新文档", description = "根据 ID 更新文档")
    public ResponseEntity<ApiResponse<DocumentResponse>> updateDocument(
            @Parameter(description = "文档ID", required = true, example = "1") @PathVariable Long id,
            @Valid @RequestBody DocumentUpdateRequest request) {
        DocumentResponse document = documentService.updateDocument(id, request);
        return ResponseEntity.ok(ApiResponse.success(document, "文档更新成功"));
    }

    /**
     * 删除文档接口
     * 
     * 接口路径：DELETE /api/v1/documents/{id}
     * 权限要求：需要登录认证，且为文档作者或管理员
     * 
     * 功能说明：
     * - 删除指定文档
     * - 物理删除（数据将无法恢复）
     * - 删除前会验证权限
     * 
     * 请求示例：
     * DELETE /api/v1/documents/1
     * Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
     * 
     * 响应示例：
     * {
     * "success": true,
     * "data": null,
     * "message": "文档删除成功"
     * }
     *
     * @param id 要删除的文档ID
     * @return 操作成功响应
     */
    @DeleteMapping("/{id}")
    @Operation(summary = "删除文档", description = "根据 ID 删除文档")
    public ResponseEntity<ApiResponse<Void>> deleteDocument(
            @Parameter(description = "文档ID", required = true, example = "1") @PathVariable Long id) {
        documentService.deleteDocument(id);
        return ResponseEntity.ok(ApiResponse.success(null, "文档删除成功"));
    }

    /**
     * 增加文档浏览量接口
     * 
     * 接口路径：POST /api/v1/documents/{id}/increment-view
     * 权限要求：无需认证
     * 
     * 功能说明：
     * - 增加文档的浏览次数计数
     * - 用于统计文档热度
     * - 建议在前端展示文档时调用
     * 
     * 请求示例：
     * POST /api/v1/documents/1/increment-view
     * 
     * 响应示例：
     * {
     * "success": true,
     * "data": null,
     * "message": "浏览量已更新"
     * }
     *
     * @param id 文档ID
     * @return 操作成功响应
     */
    @PostMapping("/{id}/increment-view")
    @Operation(summary = "增加浏览量", description = "增加文档的浏览次数")
    public ResponseEntity<ApiResponse<Void>> incrementViewCount(
            @Parameter(description = "文档ID", required = true, example = "1") @PathVariable Long id) {
        documentService.incrementViewCount(id);
        return ResponseEntity.ok(ApiResponse.success(null, "浏览量已更新"));
    }
}
